'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DAT_EP_DUP_CONNECT 3DAT "Jul 16, 2004"
.SH NAME
dat_ep_dup_connect \- establish a connection between the local Endpoint and a
remote Endpoint
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ep_dup_connect (
    IN    DAT_EP_HANDLE    ep_handle,
    IN    DAT_EP_HANDLE    dup_ep_handle,
    IN    DAT_TIMEOUT      timeout,
    IN    DAT_COUNT        private_data_size,
    IN const  DAT_PVOID    private_data,
    IN    DAT_QOS          qos
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIep_handle\fR\fR
.ad
.RS 21n
Handle for an instance of an Endpoint.
.RE

.sp
.ne 2
.na
\fB\fIdup_ep_handle\fR\fR
.ad
.RS 21n
Connected local Endpoint that specifies a requested connection remote end.
.RE

.sp
.ne 2
.na
\fB\fItimeout:\fR\fR
.ad
.RS 21n
Duration of time, in microseconds, that Consumers wait for Connection
establishment. The value of \fBDAT_TIMEOUT_INFINITE\fR represents no timeout,
indefinite wait. Values must be positive.
.RE

.sp
.ne 2
.na
\fB\fIprivate_data_size\fR\fR
.ad
.RS 21n
Size of \fIprivate_data\fR. Must be nonnegative.
.RE

.sp
.ne 2
.na
\fB\fIprivate_data\fR\fR
.ad
.RS 21n
Pointer to the private data that should be provided to the remote Consumer as
part of the Connection Request. If \fIprivate_data_size\fR is zero, then
\fIprivate_data\fR can be \fINULL\fR.
.RE

.sp
.ne 2
.na
\fB\fIqos\fR\fR
.ad
.RS 21n
Requested Quality of Service of the connection.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ep_dup_connect()\fR function requests that a connection be
established between the local Endpoint and a remote Endpoint. This operation is
used by the active/client side Consumer of the connection model. The remote
Endpoint is identified by the \fIdup_ep_handle\fR. The remote end of the
requested connection shall be the same as the remote end of the
\fIdup_ep_handle\fR. This is equivalent to requesting a connection to the same
remote IA, Connection Qualifier, and \fIconnect_flags\fR as used for
establishing the connection on duplicated Endpoints and following the same
redirections.
.sp
.LP
Upon establishing the requested connection as part of the successful completion
of this operation, the local Endpoint is bound to a Port Qualifier of the local
IA. The Port Qualifier is passed to the remote side of the requested connection
and is available to the remote Consumer in the Connection Request of the
\fBDAT_CONNECTION_REQUEST_EVENT\fR.
.sp
.LP
The Consumer-provided \fIprivate_data\fR is passed to the remote side and is
provided to the remote Consumer in the Connection Request. Consumers can
encapsulate any local Endpoint attributes that remote Consumers need to know as
part of an upper-level protocol. Providers can also provide a Provider on the
remote side any local Endpoint attributes and Transport-specific information
needed for Connection establishment by the Transport.
.sp
.LP
Upon successful completion of this operation, the local Endpoint is transferred
into \fBDAT_EP_STATE_ACTIVE_CONNECTION_PENDING\fR.
.sp
.LP
Consumers can request a specific value of \fIqos\fR. The Provider specifies
which Quality of Service it supports in documentation and in the Provider
attributes. If the local Provider or Transport does not support the requested
\fIqos\fR, the operation fails and \fBDAT_MODEL_NOT_SUPPORTED\fR is returned
synchronously. If the remote Provider does not support the requested \fIqos\fR,
the local Endpoint is automatically transitioned into a
\fBDAT_EP_STATE_UNDISCONNECTED\fR state, the connection is not established, and
the event returned on the \fIconnect_evd_handle\fR is
\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR. The same
\fBDAT_CONNECTION_EVENT_NON_PEER_REJECTED\fR event is returned if connection
cannot be established for all reasons for not establishing the connection,
except timeout, remote host not reachable, and remote peer reject. For example,
remote host is not reachable, remote Consumer is not listening on the requested
Connection Qualifier, Backlog of the requested Service Point is full, and
Transport errors. In this case, the local Endpoint is automatically
transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state.
.sp
.LP
The acceptance of the requested connection by the remote Consumer is reported
to the local Consumer through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on
the \fIconnect_evd_handle\fR of the local Endpoint.
.sp
.LP
The rejection of the connection by the remote Consumer is reported to the local
Consumer through a \fBDAT_CONNECTION_EVENT_PEER_REJECTED\fR event on the
\fIconnect_evd_handle\fR of the local Endpoint and the local Endpoint is
automatically transitioned into a \fBDAT_EP_STATE_UNDISCONNECTED\fR state.
.sp
.LP
When the Provider cannot reach the remote host or the remote host does not
respond within the Consumer-requested \fItimeout\fR, a
\fBDAT_CONNECTION_EVENT_UNREACHABLE\fR is generated on the
\fIconnect_evd_handle\fR of the Endpoint. The Endpoint transitions into a
\fBDAT_EP_STATE_DISCONNECTED\fR state.
.sp
.LP
The local Endpoint is automatically transitioned into a
\fBDAT_EP_STATE_CONNECTED\fR state when a Connection Request is accepted by the
remote Consumer and the Provider completes the Transport-specific Connection
establishment. The local Consumer is notified of the established connection
through a \fBDAT_CONNECTION_EVENT_ESTABLISHED\fR event on the
\fIconnect_evd_handle\fR of the local Endpoint.
.sp
.LP
When the \fItimeout\fR expired prior to completion of the Connection
establishment, the local Endpoint is automatically transitioned into a
\fBDAT_EP_STATE_UNDISCONNECTED\fR state and the local Consumer through a
\fBDAT_CONNECTION_EVENT_TIMED_OUT\fR event on the \fIconnect_evd_handle\fR of
the local Endpoint.
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
The \fIep_handle\fR or \fIdup_ep_handle\fR parameter is invalid.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_STATE\fR\fR
.ad
.RS 30n
A parameter is in an invalid state.
.RE

.sp
.ne 2
.na
\fB\fBDAT_MODEL_NOT_SUPPORTED\fR\fR
.ad
.RS 30n
The requested Model is not supported by the Provider. For example, requested
\fIqos\fR was not supported by the local Provider.
.RE

.SH USAGE
.sp
.LP
It is up to the Consumer to negotiate outstanding RDMA Read incoming and
outgoing with a remote peer. The outstanding RDMA Read outgoing attribute
should be smaller than the remote Endpoint outstanding RDMA Read incoming
attribute. If this is not the case, connection establishment might fail.
.sp
.LP
DAT API does not define a protocol on how remote peers exchange Endpoint
attributes. The exchange of outstanding RDMA Read incoming and outgoing
attributes of EPs is left to the Consumer ULP. The Consumer can use Private
Data for it.
.sp
.LP
If the Consumer does not care about posting RDMA Read operations or remote RDMA
Read operations on the connection, it can set the two outstanding RDMA Read
attribute values to 0.
.sp
.LP
If the Consumer does not set the two outstanding RDMA Read attributes of the
Endpoint, the Provider is free to pick up any values as a default. The Provider
is allowed to change these default values during connection setup.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Standard: uDAPL, 1.1, 1.2
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
.BR libdat (3LIB),
.BR attributes (7)
